Assignments v1

The import/assignments endpoints allows you to import the assignments properties.

Authorisation

A function key is required. The name of Key must match Software Key

Request format

Method and URL

The HTTP method and URL is as follows:

HTTP

POST https://payandbill-cloud-api.azurewebsites.net/api/import/assignments?version=1

Request Headers

Name	Type	Description
header	X-Functions-Key	Function Api Key
header	X-Software-Key	Software Key for this Integration

Request Body

Name	Type	Description
body	Assignments[]	Assignments schema

Request Body Example

Example Request Body

[
    {
      "EmployerRef": "ER1",
      "AssignmentRef": "ASSIGN1",
      "ClientRef": "CLIENT1",
      "PersonnelRef": "WORKER1",
      "DivisionRef": "DIV1",
      "DepartmentRef": "DEPT1",
      "JobTitle": "Job Title",
      "WorkLocation": "LOC1",
      "StartDate": "2019-01-01T00:00:00",
      "ExpectedEndDate": "2021-01-01T00:00:00",
      "ActualEndDate": "2022-01-01T00:00:00",
      "PurchaseOrderNumber": "PO1",
      "BookedBy": "Booker",
      "RateFrequency": "Hourly",
      "InvoiceAddressNumber": 0,
      "DeliveryAddressNumber": 0,
      "IsIncludedOnMarginReport": true,
      "JobCategoryRef": "JOB1",
      "CostCentre": "CC1",
      "ReportToClientRef": "CLIENT1",
      "InvoiceToClientRef": "CLIENT1",
      "ContactName": "Assignment Contact",
      "Notes": "Assignment Notes",
      "SalesTaxArea": "UK",
      "BookedById": "",
      "ComparatorTitle": "Comparator",
      "HolOverrideWeeks": 3.0,
      "HolOverrideHourPerc": 5.0,
      "PrevAWRWeeks": 4.0,
      "AWRQualificationWeeks": 2.0,
      "ComparatorRef": "C1",
      "IsCancelled": false,
      "EndReason": "Finished",
      "AssignmentType": "STD",
      "TimesheetFrequency": "We",
      "ContractRefPrimaryContract": "CONTRACT1",
      "ExternalNotes": "External Notes",
      "IsManualInterpretation": false,
      "SupplierContact": "Contact Name",
      "SecondaryContract": "C2",
      "IsEIRDirectClient": false,
      "IsOPWIPSApplicable": false,
      "OnlineOptions": {
        "WorkflowDescription": "Mon-Fri",
        "GroupCode": "GRP1",
        "ConsultantSTiUserLogon": "consultant@sampledata.co.uk",
        "TimesheetAuthoriserUserRef": "auth@sampledata.co.uk",
        "STiTimesheetType": 1001,
        "EscalationTypeOverride": "None",
        "IsOnlineExpenseAllowed": true
      },
      "ConsultantSplits": [
        {
          "ConsultantRef": "CONS1",
          "Split": 50.0
        },
        {
          "ConsultantRef": "CONS2",
          "Split": 50.0
        }
      ],
      "CustomerDefinedFields": {
        "CustomerDefinedField1": "1",
        "CustomerDefinedField2": "2",
        "CustomerDefinedField3": 3.0,
        "CustomerDefinedField4": 4.0,
        "CustomerDefinedField5": "5",
        "CustomerDefinedField6": "6",
        "CustomerDefinedField7": "7",
        "CustomerDefinedField8": "8"
      },
      "Rates": [
        {
          "RateType": "PayAndBill",
          "RateCode": "BAS",
          "SequenceNumber": 1,
          "PayRate": 10.0,
          "BillRate": 11.0,
          "BillingTaxCode": "Z",
          "IsDefaultRate": true,
          "RateDescription": "Basic1",
          "RateFrequency": "Hourly",
          "IsAWRable": true,
          "IsPensionable": true,
          "BillingGroup": "B1",
          "RateEffectiveDate": "2019-01-01T00:00:00",
          "RateExpiryDate": "2022-12-01T00:00:00"
        },
        {
          "RateType": "Adhoc",
          "RateCode": "HOT",
          "SequenceNumber": 5,
          "BillingTaxCode": "Z",
          "IsDefaultRate": true,
          "RateDescription": "Hotel",
          "IsAWRable": false,
          "IsPensionable": false,
          "ReceiptOption": "Receipt",
          "PayAmount": 100.0,
          "BillAmount": 120.0,
          "PayrollTaxCode": "P1"
        }
      ]
    }
  ]

Responses

Name	Type	Description
200 Ok	Results[]	successful operation
400 Bad Request	string	Invalid Json request or Invalid DB Version
401 Unauthorized	string	Invalid/Missing API Key
403 Forbidden	string	Key name does not match Software Key
403 Forbidden	string	Integration missing for Software Key or disabled
403 Forbidden	string	Pay and Bill Database not active
501 Not Implemented	string	Message Type not found/implemented
501 Not Implemented	string	Payload data not supported

Response Example

Example Response

{
    "results": [
       {
           "recordIds": [
               {
                   "field": "EmployerRef",
                   "value": "1308"
               },
               {
                   "field": "PersonnelRef",
                   "value": "503"
               }
           ],
           "importStatus": "OK",
           "errorCount": 0,
           "warningCount": 0,
           "infoCount": 0
       }
   ]
}

400 Response

Response when Invalid Json Request Body is sent to API.

Message will contain parsing error message.

400 Error Response

{
  "message": "<string>"
}

200 Response

A results array is returned which will include an item for each array item in the original request body.

Each item will identify the recordId's relevant for this message type.

Import Status, errorCount & warningCount will indicate the status of that row.

Messages will contain any error/warning messages relevant.

Note: Each row is treated as a separate commit to the database, so if multiple items are included in the import, the response will indicate which have been imported successfully & which have failed to import.

200 Ok Response

{  "results": [
    {
      "recordIds": [
          "field": "<string>",
          "value": "<string>"
       ],
       "importStatus": "<string>",
       "errorCount": <number>,
       "warningCount": <number>,
       "messages": [
         {
            "messageType": "<string>",
            "message": "<string>",
            "fieldName": "<string>"
         }
       ]
    }
  ]
}

Results

This is the response output from the import/assignments endpoint

Property	Type	Defined
RecordIds	recordIds[]	Assignments Results
ImportStatus	string	Assignments Results
ErrorCount	integer	Assignments Results
WarningCount	integer	Assignments Results
InfoCount	integer	Assignments Results
Messages	messages[]	Assignments Results

RecordIds

A record id of the imported Assignments

RecordIds

• Type: array

Property	Type	Defined
Field	string	Assignments Results
Value	string	Assignments Results

Example

{
    "recordIds": [
        {
            "field": "AssignmentRef",
            "value": "234553455"
        }
    ]
}

ImportStatus

The import status of the request

ImportStatus

• Type: string

• defined in: Assignments Results

ErrorCount

Number of errors in the request

ErrorCount

• Type: integer

• defined in: Assignments Results

WarningCount

Number of warnings in the request

WarningCount

• Type: integer

• defined in: Assignments Results

InfoCount

Number of Information messages in the request

InfoCount

• Type: integer

• defined in: Assignments Results

Messages

An output of the info, warning or error messages.

Messages

• Type: array

Property	Type	Defined
MessageType	string	Assignments Results
Message	string	Assignments Results
FieldName	string	Assignments Results
FieldValue	string	Assignments Results
ErrorId	integer	Assignments Results

Example

{
    "messages": [
        {
           "messageType": "Error",
           "message": "Required field missing or empty",
           "fieldName": "DivisionRef",
           "errorID": 1001
       }
    ]
}